5.5 The Batch Directory Synchronization Tool

MyID can be configured to update user information in MyID from the LDAP directory automatically when a user record is selected. This tool does the same thing for all accounts in MyID.

The Batch Directory Synchronization Tool is used to synchronize users imported into MyID with the latest information held in the directory. If MyID is integrated with multiple LDAP directories, all the directories will be included in the synchronization process.

You run the tool on the MyID application server, under the MyID COM user. You can run the tool from the Start menu, from the command line or as a scheduled task. For an installation containing a significant number of records, Intercede recommends that you run the synchronization tool as a scheduled task.

5.5.1 How does the Synchronization Tool work?

The Synchronization Tool processes all the records in the MyID database that are mapped to entries in an LDAP directory.

• If the record exists in MyID but the corresponding entry is no longer present in the LDAP directory, the tool can disable the user account and revoke the associated certificates.

• If the record exists in both MyID and the LDAP directory, any changes to the information held in the LDAP directory are copied to MyID.

  If the user account has been disabled in Active Directory, the user account in MyID can also be disabled and associated certificates suspended – you must set the Disable on removal from directory configuration option.

  Note: You can choose to revoke certificates instead of suspending them if the user account is suspended in the directory. Please contact customer support for details.

  Note: When you synchronize the records, if you have changed information in MyID, but not copied these changes to the directory, the changes will be overwritten by the information from the directory.

• If the whenChanged option is selected (either by selecting the whenChanged checkbox on the tool window, or by specifying the -whenchanged option on the command line) the tool processes only those records that have been updated since the last time the tool was run. The whenChanged attribute in the directory is used to identify these records. The date and time of start of the last run of the tool is stored in the MyID database.
• If the record exists in MyID, but the corresponding entry is no longer present in the directory, the behavior of the tool depends on whether the whenChanged option is selected:
• If the whenChanged option is selected, the tool will not update the MyID database to reflect the removal of the user from the directory. In this case, you must use the Active Directory Deletion Tool to synchronize the deleted users. See section 5.8, The Active Directory Deletion Tool for details.

• If the whenChanged option is not selected, the tool can disable the user account and revoke the associated certificates. This depends on whether the following options have been selected on the LDAP page of Operation Settings workflow in the Configuration category:

  • Disable on removal from directory.
  • Revoke certificates if user is removed or disabled following background directory update.

Note: When the tool is run for the first time since installation or upgrade, it runs without the whenChanged behavior, whatever options you select; this is to provide an initial successful run to set the start time of the last successful run in the database. If you select the whenChanged option, the tool displays a warning:

All changes are written directly to the MyID database and are fully audited.

5.5.2 Revoking certificates

The behavior of MyID in revoking certificates for users who have been removed from the directory depends on the combination of MyID configuration options:

Disable on removal from directory	Revoke certificates if user is removed or disabled	Behavior
NO	NO	User in MyID is unaffected.
NO	YES	User in MyID is unaffected.
YES	NO	User is disabled in MyID. Associated certificates are unaffected.
YES	YES	User is disabled in MyID and associated certificates are revoked.

5.5.3 Running the tool from the Start menu

By default, the tool runs in interactive mode from the Start menu. You can change this by editing the properties of the shortcut to incorporate the flags specified in section 5.5.4, Running the tool from the command line.

Note: Run the utility under the MyID COM user account.

1. From the Start menu, run the Batch Directory Synchronization Tool.
2. To update only those records that have been changed since the last time the Batch Directory Synchronization Tool was run, select the whenChanged option.

3. Click Synchronize.

   

   Progress is displayed both in the text area and in a progress bar towards the bottom of the dialog.

A summary of the records processed and the time taken are displayed.

For example:

Processed 122083, Updated 41752, 7027 removed from LDAP, 3161 disabled in LDAP

This means that the tool carried out the following:

• Parsed 122083 user records.
• Updated 41752 users with changes from the LDAP synchronized to MyID.
• Removed 7207 users from the LDAP.
• Disabled 3161 users in the LDAP.

Note: If the Disable on removal from directory option on the LDAP page of the Operation Settings workflow is set, the 7207 users removed from the LDAP and the 3161 users disabled in the LDAP will also be disabled in MyID.

5.5.4 Running the tool from the command line

Note: Run the utility under the MyID COM user account.

You can run the Batch Directory Synchronization Tool from the command line using the following command lines:

• Interactively – run BatchLDAPSync.exe without specifying any flags. The tool runs as described in section 5.5.3, Running the tool from the Start menu.
• Automatic execution – run the program with the -autorun flag. The dialog is displayed as described in section 5.5.3, Running the tool from the Start menu, the synchronization process starts automatically, and the dialog closes when the process has finished.
• Silently – run the program with the -silent flag. This works in the same way as ‑autorun but the dialog is not displayed. (Do not use both -silent and -autorun at the same time.)
• New changes only – run the program with the -whenchanged flag. Only those records that have been changed since the last time the Batch Directory Synchronization Tool was run are updated.

Note: The case of the command-line options is important. Use all lower-case; for example, use -whenchanged, not -whenChanged.

To record the details of the process to a specified file, add the -trace flag to the command. You can use this flag either alone or with the other flags. For example, you could run:

BatchLDAPSync.exe -silent -whenchanged -trace LDAPSync.log

If you do not specify a filename, batchldap.log in the current directory is used.

Note: You are recommended to use the -trace option when running in -silent mode.

5.5.5 Running as a scheduled task

You can run the Batch Directory Synchronization Tool as scheduled task using standard Windows functionality.

The program to be run is called BatchLDAPSync.exe and the flags available are described in section 5.5.3, Running the tool from the Start menu.

5.5.6 Troubleshooting

• Unable to communicate with server

  If the Batch Directory Synchronization Tool experiences an error communicating with an LDAP server, it displays an error similar to:

  Checking External Server ID 2
  
  Error communicating with LDAP server, aborting

  This means that the tool has been unable to communicate with that particular server. Run the tool again once you have confirmed that the network is working correctly.

  Note: If you are running the tool in -silent mode, you will see this message only if you enable the -trace option and check the log after running the tool.

• Inaccurate totals when running multiple instances

  If you are running multiple instances of the Batch Directory Synchronization Tool concurrently, the total of updated users across all instances may not match the actual total of updated users – this is because the same update may be counted by more than one instance. The updates themselves are processed correctly; only the total is inaccurate.

• Time and date discrepancies

  The tool displays local time, while the database stores UTC time; this may lead to a perception of a discrepancy between the times and dates displayed.

• Error during first run

  If an error is encountered during the first attempted synchronization the database timestamp will not be updated. The next time you run the tool, it defaults to the non-whenChanged behavior. The following warning is displayed:

  

  If this occurs, you can:

  • Shut down the tool and restart it later to perform a synchronization when the problem has been resolved, or:
  • Allow the tool to attempt to synchronize the remaining users. The timestamp will not be updated, so all users changed since the previous run will have to be processed again the next time you run the tool.

• First run with -silent and -whenchanged options

  There is no need to specify -whenchanged on the first run; you are also recommended not to use -silent on the first run so that you can see the feedback from the tool on what has been processed.

• No valid user accounts detected

  If there are no users that require synchronization, and you do not have the whenChanged option selected, the tool displays a message similar to:

  Invalid user account IDs

  This means that there are no valid user account IDs to synchronize.

• Permissions errors

  If you attempt to run the utility under a user other than the MyID COM user, you may see errors similar to the following:

  Error occurred: 80070005

  or:

  Error occurred: 80004003

  Exit the utility, then log in as the MyID COM user, and run the utility again.